home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d27 / calctime.arc / CALCTIME.DOC < prev    next >
Text File  |  1990-09-15  |  24KB  |  727 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.              ┌───────────────────────────────────────────────────┐
  7.              │                CALCTIME version 1.2               │
  8.              │                                                   │
  9.              │         DOS Command Utility Involving Time.       │
  10.              │                                                   │
  11.              │                 Reference Manual                  │
  12.              └───────────────────────────────────────────────────┘
  13.  
  14.  
  15.                                  Steve Williams
  16.                                    4380 US 29
  17.                                Tucker, Ga  30084
  18.  
  19.                       Copyright 1990. All rights reserved.
  20.  
  21.  
  22.      This version of Calctime is available as "shareware". Non-registered
  23.      users are granted a limited licence to make an evaluation copy for
  24.      trail use on a private, non-commercial basis. After evaluating this
  25.      software, you should either register your copy or discontinue it's
  26.      use. Registration entitles you to private use the software.
  27.  
  28.  
  29.                                    Disclaimer
  30.  
  31.      Use of this program acknowledges this disclaimer: "This program is
  32.      supplied as is. The author disclaims all warranties, expressed or
  33.      implied, including, without limitation, the warranties of
  34.      merchantability and of fitness of this program for any purpose. The
  35.      author assumes no liability for damages direct, indirect, or
  36.      consequential, which may result from the use or misuse of this
  37.      program."
  38.  
  39.                        Use this program at your own risk.
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.                                      - 1  -
  66.  
  67.  
  68.  
  69.  
  70.                              ┌───────────────────┐
  71.                              │ Table of Contents │
  72.                              └───────────────────┘
  73.      
  74.                            Title page and Disclaimer
  75.                              Distribution Contents
  76.                                   Introduction
  77.                                      Usage
  78.                                      Errors
  79.                               Software Information
  80.                                Registration Form
  81.  
  82.  
  83.      Distribution Contents
  84.  
  85.      The following files are included in the CALCTIME Package.
  86.  
  87.                    CALCTIME.COM
  88.                    CALCTIME.DOC
  89.  
  90.  
  91.  
  92.      Introduction
  93.  
  94.          This utility is similar to David Cusimano's program USETIME.EXE.
  95.      Mr. Cusimano did an excellent job on USETIME, but the program does not
  96.      perform the work that I required of it. So, I worked up CALCTIME to
  97.      replace and remove the limitations of USETIME.
  98.  
  99.          Calctime is capable of not only substituting time parameters in
  100.      DOS commands, but of manipulating the time and date as well; there are
  101.      also more substitutions available to the user. This utility runs in a
  102.      smaller environment, and conserves memory much better than previous
  103.      versions.
  104.  
  105.          This program is flexible and is aware of it's true name, if you
  106.      rename it, it will inform you of such on the help screen. This is not
  107.      a protection scheme, but something I've been playing around with and
  108.      working on. Calctime's awareness also has a direct effect on it's use
  109.      in conjunction with the environment list.
  110.  
  111.          Read this documentation and try out the program. If you find it to
  112.      be useful, please register it for $10(US). By supporting shareware,
  113.      you make it possible for shareware products to be produced.
  114.  
  115.          This program should be error free. If you encounter an error, I
  116.      will be more than willing to correct the error as soon as possible.
  117.      Thank You for your support.
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.                                      - 2  -
  132.  
  133.  
  134.  
  135.  
  136.      Usage
  137.  
  138.      CalcTime has the following format:
  139.  
  140.          CALCTIME [/switches] (command) [arguments and keys]  <cr>
  141.      
  142.  
  143.      SWITCHES: a few rules to live by... but, switches are optional.
  144.      
  145.      - All switches must appear before the substituting command line.
  146.      - All switches are denoted by a slash ("/") in front of each switch.
  147.      - Each switch must be separated by at least one space.
  148.      - And, switches may not contain any spaces in them.
  149.  
  150.      The following switches directly effect the time and date substitution
  151.      keys. All these switches are cumulative in nature.
  152.  
  153.      Y±Σ : adds or subtracts years from the current value.
  154.      M±Σ : adds or subtracts months from the current value.
  155.      D±Σ : adds or subtracts days from the current value.
  156.  
  157.      H±Σ : adds or subtracts hours from the current value.
  158.      I±Σ : adds or subtracts minutes from the current value.
  159.      S±Σ : adds or subtracts seconds from the current value.
  160.  
  161.      - "±"  denotes a plus(+) or minus(-), for addition and subtraction.
  162.      - "Σ"  denotes an integer or another substitution key.
  163.  
  164.          An integer I can see, but another substitution key? Here's an
  165.      example, what if you are using the current day + the current month for
  166.      a dynamic password scheme in some program. Calctime can now be used to
  167.      automate that program's execution. Most people will not have use for
  168.      Cacltime's ability to add(or subtract) keys with one another, but
  169.      someone might, so I included it.
  170.  
  171.      1-7 :
  172.          The switches 1-7 are used to change the logical "beginning of the
  173.      week" weekday. Does this sound strange? For most of us, the week
  174.      begins on Monday (or is it Friday afternoon), but the calender starts
  175.      on Sunday, and the motion picture industry begins the week on Friday.
  176.      This switch is used to select the beginning weekday for use in
  177.      calculating the week number of the year. This switch is designed for
  178.      use with business purposes in mind. If you are not going to be using
  179.      the "K" key, do not be concerned. If you will be using the "K" key,
  180.      please note that this utility assumes the week begins on Sunday. To
  181.      change this assumption, use the "1" - "7" switches:
  182.  
  183.      The numbers correspond to days in this fashion:
  184.      /1 - Sunday   (the default value)
  185.      /2 - Tuesday
  186.      /3 - Monday
  187.      /4 - Wednesday
  188.      /5 - Thursday
  189.      /6 - Friday
  190.      /7 - Saturday
  191.  
  192.  
  193.      P:
  194.          The "P" switch will Print the command line to the standard output
  195.      device before executing it.
  196.  
  197.                                      - 3  -
  198.  
  199.  
  200.  
  201.  
  202.      R:
  203.          The "R" switch will cause Calctime to Read the current time (in
  204.      absolute seconds since 1970) from the standard input device. There
  205.      will be no prompt displayed by Calctime, thus, improper use can hold
  206.      up an automated batch file.
  207.  
  208.          This switch can be extremely useful for batch files executing near
  209.      a time or date boundary (such as midnight). The R switch causes
  210.      Calctime to set the variable clock key (denoted by #) to absolute
  211.      seconds in time. This value is read from the standard input device and
  212.      is the number of seconds that have elapsed since Jan 1, 1970. This
  213.      value can be stored to a file using DOS redirection and the "Z" key.
  214.  
  215.          The general idea is to save a time value to a temporary file, and
  216.      then use that file (via DOS redirection) as input to the /R switch. To
  217.      save the current time value, use the Z substitution key. The following
  218.      example shows this procedure:
  219.  
  220.      CALCTIME echo $z > holdtime    { store absolute seconds to temp file }
  221.      CALCTIME /r copy c:\daily\files\*.* c:\archive\#m-#d-#y.dat < holdtime
  222.                                     { use the saved time in the next cmd  }
  223.      DEL holdtime  { delete the temp file after your done with it }
  224.  
  225.      Although this example doesn't really show off /R's usefulness, try to
  226.      imagine a batch file that is much longer and occurs just before
  227.      midnight. Although it has not been wise to set up a system to do
  228.      day-end processing before the midnight barrier, this program does give
  229.      you the power and flexibility to do such systems.
  230.  
  231.  
  232.      E:
  233.          The "E" switch tells Calctime to search the Environment for itself
  234.      and a set of switches to be substituted at the point where the /E
  235.      switch was encountered.
  236.  
  237.          If no environment variable is not found, Calctime will report this
  238.      information to the standard output device and will then resume
  239.      processing; Calctime does not consider this occurrence to be an error.
  240.  
  241.          Calctime has an ability not mentioned yet, but you need to be
  242.      aware of it before using /E switch. Calctime can be renamed (as with
  243.      all programs), but Calctime can sense this change and will adapt
  244.      itself to this change.
  245.  
  246.          When using the /E switch, Calctime will search the environment
  247.      list looking for itself(whatever you've renamed it). The default is
  248.      CALCTIME=....
  249.      But, if you rename Calctime to CT.COM, this utility will search for
  250.      CT=.... in the environment list.
  251.  
  252.          If you're not familiar with the environment list, I suggest you
  253.      read your DOS manual, especially the DOS command "SET".
  254.  
  255.          The environment variable is only good with switches. Placing
  256.      anything else on the environment line will result in an error message.
  257.  
  258.      Ex: set CALCTIME=/y+1 /m-1 /h+23            {valid: switches only}
  259.          set CALCTIME=/y+1 echo the time is $t   {invalid: non-switches}
  260.  
  261.  
  262.  
  263.                                      - 4  -
  264.  
  265.  
  266.  
  267.  
  268.      L :
  269.          The L switch tells calctime to advance the variable time set to
  270.      Last day of the month. This is in conjunction with any other date
  271.      manipulations already performed.
  272.  
  273.      Examples:
  274.  
  275.          Calctime /L echo #t <cr>.
  276.      This would print the timestamp giving the date as the last day of this
  277.      month.
  278.  
  279.          Calctime /m-1 /L echo #t <cr>.
  280.      This gives the timestamp date of the last day of last month.
  281.  
  282.          Calctime /l /m-1 echo #t <cr>.
  283.      This would give the timestamp with the date of the last day of this
  284.      month, but with last month's name. Of course, if this is a 31 day
  285.      month, the result will most likely be last month the 30th. Save for
  286.      July and February.
  287.  
  288.          Calctime /m-1 /l /d+1 echo #t <cr>.
  289.      This will give the timestamp for the beginning of this month. Of
  290.      course, other combinations are possible on this theme.
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.                                      - 5  -
  330.  
  331.  
  332.  
  333.  
  334.      KEYS: what are they and how do they work:
  335.  
  336.          There are currently three keys; the `$' key, the `#' key,
  337.      and the `!' key. The first two ($ and #) are time substitution keys as
  338.      follows, and the last (!) is a special difference key.
  339.  
  340.          Each one represents a certain date-time variable set used in the
  341.      program. The default values for all keys is the current time. If the
  342.      /R switch is used, then the `#' key is set to the read in value time.
  343.  
  344.      $:  The dollar sign represents the current static time and will not
  345.      change through out the program's execution. Any reference to a $
  346.      substitution will yield the current clock time of your machine.
  347.  
  348.      #:  The pound sign represents the variable time set and is changed by
  349.      use of the previously mentioned switches that manipulate the time and
  350.      date. This key defaults to the current time if no switches are
  351.      encountered. If the /R switch is used, then this key is changed to the
  352.      time calculated from the read in value. (This will destroy any
  353.      previous time manipulations preceding the /R switch.)
  354.  
  355.          The precedence of the switches is fairly simple in nature. Each
  356.      switch is processed from left to right with only one exception, the /R
  357.      switch. All time manipulative switches that occur before the /R switch
  358.      will be lost, and all the switches after the /R switch will effect the
  359.      new variable time set. All the time manipulative switches are
  360.      cumulative in nature; however, the /R switch changes the effective
  361.      variable time set. So, adding a year before the /R switch will have no
  362.      effect of the variable time set(`#' set), it will have the time
  363.      calculated from the read in value. Of course, adding a year AFTER the
  364.      /R switch will effect the variable time set in the expected manner.
  365.  
  366.      The ! key:
  367.          This is the difference key. It calculates the difference between
  368.      the $ key and the # key. This is a trivial feature for people who
  369.      aspire to be Mr. Spock from Star Trek(copyrighted, Paramount). Or
  370.      perhaps it's just for the curious. It is really just an added feature
  371.      that might can be useful to help keep track of batch file execution
  372.      times, and other stuff like that. In any event, it is only valid with
  373.      the following key substitutions:
  374.  
  375.      Y - years portion of the time difference
  376.      M - month portion
  377.      D - days portion
  378.      H - hours portion
  379.      M - minutes portion
  380.      S - seconds portion
  381.  
  382.      T - combination of ALL the above.
  383.  
  384.          The use that came to mind initially was for it is to display the
  385.      time since the beginning of something. An example is the display of
  386.      how long Joe's BBS been online at the time of your login (in this
  387.      case, a friend of mine is using it for this function). But, more
  388.      creative minds than mine should find other deranged and perhaps even
  389.      useful purposes for it.
  390.  
  391.  
  392.  
  393.  
  394.  
  395.                                      - 6  -
  396.  
  397.  
  398.  
  399.  
  400.  
  401.      Substitutions:
  402.  
  403.      A:  gives the day number of the year (1-366).
  404.      B:  reports the "beginning of week" day name (Sunday - Saturday).
  405.      C:  gives full month name (January - December).
  406.      D:  inserts the date of the month (01 - 31).
  407.      E:  gives the full year (1970 - 20??).
  408.      F:  filled with the full day name of the week (Monday - Sunday).
  409.      G:  hours in the 12 hour notation (01 - 12).
  410.      H:  hours in the 24 hour notation (00 - 23), military style.
  411.      I:  minutes (00 - 59).
  412.      J:  not used (yet).
  413.      K:  gives the week number of the year based on the value of B (01-53).
  414.      L:  Last day: gives the date unless it's the last day of the month,
  415.                    at which it gives "LD", instead (01 - LD).
  416.      M:  inserts the month number (01 - 12).
  417.      N:  gives the number of sec.s elapsed since midnight (00000-86399).
  418.      O:  reports the month in 3 character format (JAN - DEC).
  419.      P:  not used.
  420.      Q:  gives the quarter of the year, based on the 3 month cycle (1 - 4).
  421.      R:  not used.
  422.      S:  seconds (00 - 59).
  423.      T:  this gives a full bodied time stamp.
  424.                                         Ex: 10:02 pm, Friday, June 15, 1990
  425.      U:  not used.
  426.      V:  not used.
  427.      W:  this gives the 3 character format day of the week (MON - SUN).
  428.      X:  reports AM or PM (am - pm).
  429.      Y:  gives the two digit year number (00 - 99).
  430.      Z:  this gives the number of sec.s elapsed since Jan. 1, 1970. This
  431.          value was chosen since it's the UNIX standard time reference.
  432.  
  433.      $, #, and/or !:
  434.          double keys give a single key in the substituted command line to
  435.          be executed.
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.                                      - 7  -
  462.  
  463.  
  464.  
  465.  
  466.      Errors
  467.  
  468.          By overlaying itself, Calctime allows DOS errors to be returned to
  469.      the calling program of batch file. Also, if Calctime itself occurs an
  470.      error, it returns the error code of 101.
  471.  
  472.          There are about a dozen errors that can occur and be detected.
  473.      Some are user related, others are software related. The possible
  474.      errors are:
  475.  
  476.      Clock counter warped out of bounds - this error results when you out
  477.      step the boundaries of the time modifier switches, like /y-1000; this
  478.      will give an error.
  479.  
  480.      DOS command required - Calctime requires a command appear after the
  481.      switches. This error will not occur if you give an invalid command.
  482.      This only appears in the complete absence of any command parameter.
  483.      Ex: CALCTIME /y+3 /h-1 <cr>   {no command parameter specified}.
  484.  
  485.      Error #0 does not exist - if you receive this error, then the program
  486.      has been hacked by some user. Please report this to me, the
  487.      programmer, and discontinue use of this utility.
  488.  
  489.      Improper Spawn Procedure, Contact Programmer - this error should never
  490.      occur since it was instantiated for debugging purposes. If it does
  491.      occur, the problem is caused by Calctime not being able to properly
  492.      create a child process. This is a DOS call related error and could be
  493.      caused by a possible DOS incompatibility problem, it might also
  494.      represent other serious problems. This error usually occurs when
  495.      Calctime cannot find command.com (or what ever you have assigned to
  496.      COMSPEC in the environment list).
  497.  
  498.      Invalid Input, value must be a positive integer - you used non-numeric
  499.      input on the \R switch input request. Please use only positive numeric
  500.      input values.
  501.  
  502.      Invalid operator detected in switch - use only + and - operator in the
  503.      time modifying switches. This will only occur during the YMDHIS
  504.      switches. This error will not occur if the switch was invalid.
  505.  
  506.      Invalid parameter on environment line - a non-switch parameter was
  507.      found on the environment line. Remember, only switches may appear on
  508.      the environment line.
  509.  
  510.      Invalid switch in command line - self explanatory. You attempted to
  511.      use a switch that is not defined in this program. See switches for a
  512.      list of valid switches (they include Y,M,D,H,I,S,P,R, and E).
  513.  
  514.      Not Enough Memory to run spawned file - The dreaded OUT OF MEMORY
  515.      error. There's nothing I can do to help you on this one. You should
  516.      see about using your available memory more carefully, or run smaller
  517.      programs. This error is returned by a DOS call and is out of my
  518.      control. Since Calctime overlays itself in memory, it's doing it's
  519.      best to conserve memory.
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.                                      - 8  -
  528.  
  529.  
  530.  
  531.  
  532.  
  533.      Resulting command line too long - after all substitutions and
  534.      modifications have been made to generate the desired executable
  535.      command line, the length is greater than 127 characters. The DOS limit
  536.      is 128, my limit is 127. Try to shorten you command line. Note If
  537.      you're trying to execute a batch file on this erred line, please note
  538.      that the effective length is shortened to 116 characters. This was
  539.      necessary to conform program to memory conservation standards.
  540.  
  541.      Switch operation too long -  a valid switch was encountered, but
  542.      contained too many parameters. This error is resultant in the misuse
  543.      of the YMDHIS switches.
  544.  
  545.      Switch too long - a switch was found to be longer than allowed. This
  546.      error is resultant in the misuse of the ERP switches. These switches
  547.      are stand alone and require no parameters.
  548.  
  549.      Third token in switch operation not valid - you used an invalid
  550.      substitution key or value in a valid switch (YMDHIS) with a valid
  551.      operator.
  552.  
  553.      Unable to create appended child process - attempt to create the child
  554.      process failed. Same as Improper Spawning Error(see above).
  555.  
  556.      Unknown error occurred while spawning, Contact Programmer - and yet
  557.      one more of these mysterious spawning error detectors. Please see
  558.      Improper Spawning error above.
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.                                      - 9  -
  594.  
  595.  
  596.  
  597.  
  598.      Software Information
  599.  
  600.          This version limits time to the boundaries to an unsigned long
  601.      integer. The origin being Jan. 1st, 1970, and the highest allowable
  602.      date of about 6:30 am, Feb. 6, 2106. If this utility is still around,
  603.      you can bet I've modified it by then to count much, much higher! But
  604.      for now, I want to avoid using floating point values, so I used the
  605.      largest integer type available. Needless to say, this program just
  606.      might out live me, and it's designed to certainly out live all of
  607.      today's PC's (they have a limited clock capability stopping at the
  608.      year 2100).
  609.  
  610.          I've spent a great deal of time and effort to keep all time and
  611.      date manipulations and calculations accurate. This program has been
  612.      written to conform to the Gregorian Calendar System created circa
  613.      1572, and adopted by the United States of America in 1752. This
  614.      program does not take into account the century leap year exception of
  615.      this Greg. Cal. System because of it's incidental usage in the 20th
  616.      century. Under the Greg. Cal. Sys., centuries not divisible by 4 are
  617.      NOT to be leap years. The year 2000 just happens to be one of the leap
  618.      centuries. All other calculations should be accurate in their nature.
  619.      Pls. contact me if you run across a calculation error. Thanx.
  620.  
  621.          There is a batch file limitation; you can not use the GOTO batch
  622.      command with Calctime, as it will not give the desired results.
  623.  
  624.      Example:
  625.          calctime GOTO $F
  626.          rem the above doesn't execute the GOTO and continues to this line.
  627.          goto end
  628.          :Saturday
  629.          rem this portion is NEVER executed.
  630.          :end
  631.          rem batch file ends here.
  632.  
  633.  
  634.          Calctime overlays itself to execute it's command line. This saves
  635.      approximately 65K in overall memory usage. Needless to say, if memory
  636.      is a problem; this utility should work well for you. If you use
  637.      Calctime to run another batch file, there will be about 4K overhead
  638.      from a second Command.com (which will be overlaid on top of Calctime's
  639.      space). Otherwise, you'll get back all memory used by Calctime. Note:
  640.      the second Command.com is necessary for the called batch file to be
  641.      able to return to the calling batch file.
  642.  
  643.          This program expands on a "standard" adopted from David Cusimano's
  644.      program USETIME.EXE. Calctime.com has been developed specifically to
  645.      remove usetime.exe's limitations, as well as serve my own needs for
  646.      flexible time variables. I hope you find it to be a useful program.
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.                                      - 10 -
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.      Send $10(US) Check or Money Order to: Steve Williams
  668.                                            4380 U.S. 29
  669.                                            Tucker, Ga.  30084
  670.  
  671.  
  672.  
  673.      Name:___________________________  Company/BBS:_______________________
  674.  
  675.      Address:_____________________________________________________________
  676.  
  677.      City:___________________________  State:_______  Zip:________________
  678.  
  679.      Voice Day Phone:________________  Evening:___________________________
  680.  
  681.      Data/BBS Phone:______________________________________________________
  682.  
  683.      Signature:___________________________________________________________
  684.  
  685.      Comments/Suggestions:________________________________________________
  686.  
  687.      _____________________________________________________________________
  688.  
  689.      _____________________________________________________________________
  690.  
  691.      _____________________________________________________________________
  692.  
  693.      _____________________________________________________________________
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.  
  703.  
  704.  
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.                                      - 11 -
  726.  
  727.